The ShinyStudio project is an orchestration of various open-source solutions with the goal of providing:
There are two distributions of ShinyStudio, the image and the stack.
The ShinyStudio image, hosted on DockerHub, builds upon the Rocker project to include:
The image is great for a personal instance, a quick demo, or the building blocks for a very customized setup.
The ShinyStudio stack builds upon the image to incorporate:
The stack provides a more enterprise-ready distribution, as NGINX provides an simple solution for HTTPS, and site usage is stored in InfluxDB.
Moreover, each component of the stack is run in a Docker container for reproducibility, scalability, and security. Only the NGINX port is exposed on the host system; all communication between ShinyProxy and other components happens inside an isolated Docker network.
The setup has been verified to work on each of Docker (for Linux) and Docker Desktop (for Mac and Windows).
Note: when upgrading ShinyStudio, setup from scratch and migrate existing content/settings afterward.
The instructions below assume a functional instance of Docker.
Note: Setup must be run as a non-root user.
To download and run the ShinyStudio image from DockerHub, first, create a docker network named shinystudio-net:
docker network create shinystudio-net
Then, execute docker run in the terminal for your OS:
docker run -d --restart always --name shinyproxy \
--network shinystudio-net \
-v /var/run/docker.sock:/var/run/docker.sock \
-e USERID=$USERID \
-e USER=$USER \
-e PASSWORD=password \
-e CONTENTPATH="${HOME}/ShinyStudio" \
-e SITEPORT=8080 \
-p 8080:8080 \
dm3ll3n/shinystudio
docker run -d --restart always --name shinyproxy `
--network shinystudio-net `
-v /var/run/docker.sock:/var/run/docker.sock `
-e USERID=1000 `
-e USER=$env:USERNAME `
-e PASSWORD=password `
-e CONTENTPATH="/host_mnt/c/Users/$env:USERNAME/ShinyStudio" `
-e SITEPORT=8080 `
-p 8080:8080 `
dm3ll3n/shinystudio
Notice the unique form of the path for the
CONTENTPATHvariable in the Windows setup.
Once complete, open a web browser and navigate to http://<hostname>:8080. Log in with your username and the password password.
The stack distribution of ShinyStudio is delivered through the GitHub repo and introduces two additional requirements:
First, clone the repo and enter the new directory:
git clone https://github.com/dm3ll3n/ShinyStudio
cd ShinyStudio
Complete the setup using either the provided scripts or by executing the commands manually. Once complete, open a web browser and navigate to http://<hostname>:8080.
The default logins are:
| username | password |
|---|---|
| user | user |
| admin | admin |
| superadmin | superadmin |
The quickest way to get up-and-running is to use the provided control scripts. The scripts are provided as both Bash scripts (.sh) and PowerShell scripts (.ps1); use the script that is appropriate for your OS.
The command below will create a new site configuration based on the template at configs/template, then start it.
# Bash
./control.sh start 8080
# OR
# PowerShell
./control.ps1 start 8080
To perform the setup without the provided scripts, first copy the configs/template directory and rename it according to the HTTP port that this new site will listen on.
# Bash
cp -R 'configs/template' 'configs/8080'
# OR
# PowerShell
Copy-Item 'configs/template' 'configs/8080' -Recurse
Then, set the required environment variables followed by docker-compose up:
# specify the site's port (./configs/<port>)
export SITEPORT=8080
# specify where to store content.
export CONTENTPATH="./content"
# specify the HTTPS port defined in 'nginx.conf',
# or use a random high-port if SSL is not enabled.
export HTTPSPORT=$((50000 + RANDOM % 10000))
# use the current user ID and user name.
export USERID=$UID
export USER
# build and start the project; the project name is required.
docker-compose -p "shinystudio_${SITEPORT}" up -d --build
# specify the site's port (./configs/<port>)
$env:SITEPORT = '8080'
# specify where to store content.
$env:CONTENTPATH = '/host_mnt/c/Users/$env:USERNAME/ShinyStudio/content'
# specify the HTTPS port defined in 'nginx.conf',
# or use a random high-port if SSL is not enabled.
$env:HTTPSPORT = (Get-Random -Minimum 50000 -Maximum 60000).ToString()
# use the current user ID and user name.
$env:USER = $env:USERNAME
$env:USERID = 1000
# build and start the project; the project name is required.
docker-compose -p "shinystudio_$($env:SITEPORT)" up -d --build
Open your IDE of choice and notice two important directories:
Files must be saved in either of these two directories in order to persist between sessions.
These two folders are shared between instances RStudio, VS Code, and Shiny Server. So, creating new content is as simple as saving a file to the appropriate directory.
The ShinyStudio image comes with…
…and ODBC drivers for:
These are persistent because they are built into the image.
| Persistent | |
|---|---|
| __ShinyStudio__ directory | Yes |
| __Personal__ directory | Yes |
| Other directories | No |
| R Libraries | Yes |
| Python Packages | Yes |
| PowerShell Modules | Yes |
| RStudio User Settings | Yes |
| VS Code User Settings | Yes |
| Installed Apps | No |
| Installed Drivers | No |
The information below only applies to the ShinyStudio stack.
Many of the configuration options are accessible through the ShinyProxy configuration file, application.yml. Here, you can change the site title, change the authentication mechanism, and further refine access.
Review the ShinyProxy configuration documentation for all options.
ShinyProxy supports various authentication mechanisms (basic, LDAP, social, …).
To change from basic auth (default) to LDAP auth, open the site’s configuration file (configs/8080/application.yml), locate the section below…
authentication: simple
users:
- name: superadmin
password: *change*me*
groups: superadmins
- name: admin
password: *change*me*
groups: admins
- name: user
password: *change*me*
groups: readers
…and replace it with the following, after providing values appropriate for your environment:
ldap:
url: ldap://mydomain.com/DC=mydomain,DC=com
manager-dn: CN=svc.user,OU=Users,DC=mydomain,DC=com
manager-password: ...
user-search-base:
user-search-filter: (sAMAccountName={0})
group-search-base: OU=Groups
group-search-filter: (member={0})
Afterward, you may want to refine access to various apps using the access-groups option available to each:
access-groups: [ "reader-group", "admin-group", "superadmin-group" ]
To encrypt communication over HTTPS, edit the provided NGINX configuration file for the site in question (configs/8080/nginx.conf).
First, place the site’s certificate and key in configs/8080/certs/.
Then, uncomment the designated lines in nginx.conf and supply the desired HTTPS port in the three sections indicated in the file.
Finally, restart the site with:
./control.[sh/ps1] restart 8080
If configured properly, HTTP requests to ShinyProxy will be redirected to HTTPS.